Skip to content

Stabilize GetX 5 RC for Flutter 3.47.9 and 3.50.0 - #3488

Open
mahanpyk wants to merge 23 commits into
jonataslaw:latest-getx5-RCfrom
mahanpyk:getx5-rc-stabilize
Open

mahanpyk wants to merge 23 commits into
jonataslaw:latest-getx5-RCfrom
mahanpyk:getx5-rc-stabilize

Conversation

@mahanpyk

@mahanpyk mahanpyk commented Nov 5, 2026 •

Copy link
Copy Markdown

The GetX 5 RC branch retained newer APIs but had fallen behind Flutter compatibility work on master. This PR stabilizes its existing state, DI, Navigator 2, overlay and GetConnect contracts, reconciles applicable master fixes, and provides comprehensive, current migration and project documentation.

Runtime and compatibility

  • Validate Flutter 3.47.9 / Dart 3.13.7 and update CI and the example Android/iOS hosts. Retain Flutter's bundled Material/Cupertino types; standalone UI types are a separate migration.
  • Fix Rx subscription recovery, collection assignment, controller/binding disposal, queued-job recovery and StateMixin asynchronous completion contracts.
  • Preserve typed route results, middleware decisions, nested navigation, back vetoes and overlay cleanup. Add opt-in named-route history restoration with validated arguments, bounded payloads, guarded fallbacks and fresh controllers/completers after process recovery.
  • Complete IO/browser HTTP error and authentication paths, response-modifier removal, WebSocket replacement/disposal and browser JS/WASM transport coverage.
  • Selectively port mutable default Rx collections and optional navigation contexts from merged #3472, preserving the RC's explicit page/overlay closing contract. The release scope records master reconciliation.
  • Migrate GetNavigator (both constructors), GetDelegate and GetRouterOutlet.pickPages from deprecated onPopPage to onDidRemovePage. Keep back policy in GetPage.canPop / PopScope, forward typed results at route completion, and remove the specific committed history entry. Custom low-level callbacks must migrate their named argument and contract; see the migration guide.
  • Add device probes and native harnesses for system/predictive back and cold restoration. CI builds the Android APK/harness; native target acceptance was run separately.

Comprehensive documentation

  • English and Persian now cover the same 32 project-guide topics, with 24 identical Dart examples: state/Rx/workers, DI/bindings/services, navigation/overlays/restoration, localization/theme, HTTP/modifiers/auth/WebSocket, middleware, context/platform/configuration, local/responsive/cached views, queue semantics, tests, migration, candidate changes and known limits.
  • All 15 other translated READMEs receive localized RC changes and corrected recipes in their bodies, including async registration, middleware, network modifiers, app settings, contexts and lifetimes. Their explanations/body headings are retained; they are not claimed to be newly expanded full translations of every English paragraph.
  • Repair translated tables of contents and local links, remove unsupported performance claims, and retain historical GetX 2 examples as historical material.
  • Update the grouped CHANGELOG, migration references, example instructions and source-install/publication guidance.

Navigator regression evidence

Before the callback migration, targeted tests reproduced two failures: native pushReplacement left the typed result pending and stale history; replacing a covered page retained its history entry. The new callback API also failed to compile before implementation. The implementation completes the removed page result separately and identifies its history entry by page/completer identity, so delayed notifications cannot delete a same-key replacement.

Nine focused tests cover both GetNavigator constructors, normal typed pop, imperative replacement, covered-page replacement, stale notifications, generated-route result ownership, and default/custom nested outlet forwarding. Back vetoes, Cupertino swipe cancellation/completion and restoration remain covered by the existing regression suites and fresh Android acceptance. The Chrome fixture uses an explicit hash-enabled delegate because Flutter's widget-test host has no valid base href; production PathUrlStrategy is exercised by the separate browser probes.

Review follow-up

Review confirmed the separation between native typed result completion and committed page removal, identity-based history cleanup, stale notifications, generated-route result ownership, vetoes and nested forwarding. Library follow-up changes only formatting and declaration order; parser-token comparison verifies unchanged implementation tokens after accounting for the unchanged moved method and trailing commas. GetNavigator and the affected test constructor now follow neighboring indentation; GetPageRoute keeps its constructor and fields before lifecycle overrides.

The review also found and fixed a browser acceptance probe bug: a child could remain current inside a covered parent Navigator and overwrite the visible root page's reported state. A real-browser regression first failed on exit from nested history, then all 16 ordinary scenarios pass in JS and in WASM after checking all enclosing routes. This fixes observation, not navigation rendering. The CHANGELOG records it.

Live Chrome acceptance uses the web-specific browser_navigation_probe entry point: it renders home/second/home/nested/home, hot reloads successfully, and records no runtime errors. The device_navigation_probe remains scoped to native acceptance.

Flutter 3.50 compatibility

  • Bump the unreleased candidate to 5.0.0-release-candidate-9.4.1. The test matrix covers Flutter 3.47.9 / Dart 3.13.7 and Flutter 3.50.0 / Dart 3.14.0. Keep the existing SDK minimum and bundled Material/Cupertino public types. Flutter 3.50 deprecates those imports.
  • Flutter 3.50 rejects the example's previous AGP 9.1.0. The Navigator 2 Android example now uses AGP 9.1.1 and Kotlin 2.4.10, which meet the SDK’s validation requirements. The runner builds Android on Flutter 3.50.0.
  • On Flutter 3.50.0, all 18 real-Chrome navigation checks per JS/WASM lane pass, including encoded deep links and refresh. Both 8-step history lanes and the two-step pure Flutter encoding control pass. CI requires the strict checks on 3.50.0. The Flutter 3.47.9 encoding limitation remains documented.
  • Flutter 3.50.0 local validation also passed 519 root tests, 30 Chrome widget tests, both example test suites (5 + 1), and 14 browser transport tests per JS/WASM lane. Analyzer reports zero errors/warnings and informational notices for the deprecated bundled imports and existing lints. The Navigator 2 example builds and reaches its dashboard on an iOS 26.5 simulator.

Validation

  • Commit d7eb4435 passed all three fork CI jobs for Flutter 3.47.9, Flutter 3.50.0 and Android. The locally built Flutter 3.50.0 debug APK reached the Navigator 2 dashboard on an API 36 emulator. Package dry-run passed with zero warnings.

  • Previous review head 7602cb22: fork CI passed both test and Android jobs, including the new JS/WASM nested-exit regression and the existing history gates. CI now also runs all nine callback/removal regressions on Chrome, alongside the existing transport/navigation/history checks, JS/WASM builds and Android APK/harness compilation.

  • Local root suite 519/519, example suites 5/5 + 1/1, focused Chrome suite 9/9, and separate README consumer 6/6 pass. Direct root Dart analyzer: zero errors/warnings, 8 existing initializing-formal infos; the two onPopPage deprecation infos are gone. Live web hot reload succeeds.

  • All 16 instrumented lines in the two new runtime methods (didRemovePage, didComplete) are hit by the root coverage run; this is scoped line coverage, not a whole-library or branch-coverage claim.

  • The 24 shared English/Persian Dart examples remain identical. The 24 examples plus 13 corrected translation recipes were compiled/analyzed in the external consumer, with zero errors/warnings; its six interaction tests were rerun against this runtime.

  • 1,100 relative file/anchor links resolve across the 17 root READMEs. Callback migration guidance is included in every README and the grouped CHANGELOG. Package dry-run: zero warnings.

  • Fresh Android profile/AOT acceptance for this migration: API 24 6/6, API 36 10/10, and 3 cold same-task process-restoration cycles per lane. The API 36 suite includes real system/predictive-back cancel/commit, vetoes and root activity exit. The cold checks verify new PID/BOOT, preserved counter/note/history, fresh typed result 42 and disposal.

  • Native source fingerprint R11-17f78e1ac442d8d5; installed APK SHA-256 31786e2061f993a0ca2f70238abde1b45304d1b18ea87a09b6791b7099eb307d matched on both lanes. All 147 recorded runtime/host input hashes matched source 7b01688a. The subsequent review changes library formatting/declaration order with matching implementation tokens, plus the web-only probe and its test. No fresh native acceptance is claimed for these review commits. Task-owned packages were removed and its two dedicated emulators stopped after acceptance.

  • Physical iOS acceptance from earlier rounds (4 back/gesture scenarios and 3 cold cycles) remains historical evidence on those recorded artifacts; no new physical iOS run is claimed for this callback migration.

Scope and related work

The package is the unreleased 5.0.0-release-candidate-9.4.1. URI-only startup on full browser reload remains distinct from route-state replay during back and forward. The browser guide records the encoding results by Flutter version.

Runtime topics overlap the open master-targeted #3480, response-modifier work #3485, and migration documentation #3487. This PR integrates and regression-tests the relevant contracts against latest-getx5-RC; those topics and merged master fixes are not presented as new discoveries. An earlier partial onDidRemovePage attempt, #3258, was closed without merge; its complete available discussion/timeline was checked. This follow-up integrates the migration into the existing RC stabilization PR and does not treat that earlier attempt as a merged fix. No blanket master merge or standalone UI migration is included.

The upstream workflow for the latest commit requires maintainer approval.

Fix reactive subscriptions, disposal, queues, collection assignment, scoped
bindings and state completion. Correct navigation results, middleware,
overlays, restoration and app configuration, with focused regressions.

Refresh RC migration documentation and examples, and prepare the CI matrix.

Validation on Flutter 3.47.5 / Dart 3.13.4: 327 root tests and 6 example
tests pass; analyzer has no errors or warnings, with 5 existing deprecated
infos. JavaScript and WASM web builds pass. Target SDK 3.47.8/3.47.9 and
native-device verification remain pending; this is not a stable release.
Adapt app route maps, apply live configuration changes, and preserve root-owned routing, binding and snackbar state. Track registration generations and shared widget lifetimes so scope cleanup respects replacement instances and the current autoRemove policy.

Fix typed HTTP callbacks, authentication request replacement, body timeouts and IO socket connection cleanup. Complete snackbar cancellation and teardown, and port the remaining selected navigation, lifecycle and TickerMode compatibility fixes.

Add 97 regression and loopback integration tests, and run the public facade and Rx smoke tests in Chrome CI. Verified locally with Flutter 3.47.5/Dart 3.13.4: 424 root tests, 6 example tests, 12 Chrome tests, analyzer without errors or warnings, and JavaScript/WASM builds. The SDK and dependencies are unchanged; final release gates remain open.
Complete XHR error, timeout, abort and close-during-body handling. Send WebSocket text and binary values using JS interop, retain messages during reconnect, close replaced IO/browser transports and release heartbeat resources.

Document the existing queue cancellation and concurrent futurize contracts, remove a redundant formal parameter modifier for Dart 3.13, and stop tracking generated example files. Add real local TLS controls, browser network fixtures and repeatable JS/WASM navigation probes with strict encoded-query diagnostics.

Verified with the installed Flutter 3.47.5/Dart 3.13.4: 445 root tests, 6 example tests, 12 Chrome smoke tests, 14 browser transport cases on each JS/WASM runner, and 13 ordinary navigation scenarios on each JS/WASM artifact. Strict encoded query remains a recorded Flutter-control reproduction; SDK installation and final release gates remain deferred.
Require the selected stable Flutter 3.47.9 and Dart 3.13.7 baseline in the package and examples, and pin CI to that version. Prepare an unpublished RC 9.4.0 version instead of reusing the older published candidate number.

Modernize the Navigator 2 example's Android host using the installed SDK's Gradle plugin DSL, namespace, Java/Kotlin 17 settings and Android defaults. Preserve application identity and add an Android arm64 debug-build CI gate.

Update the SDK, example and migration documentation, including the independently reproduced Flutter web-history encoding limitation and its upstream correction. Current-SDK root/example, browser transport, consumer and iOS checks pass; the strict encoding gate remains an explicit SDK limitation rather than a claimed GetX fix.
Port the constructor fix from upstream 28cb1bb (jonataslaw#3472). The new regression suite failed for all three default constructors before this change and now passes 9 tests, preserving explicit backing collections and immutable inputs.
Port the nullable-root context access from upstream 28cb1bb (jonataslaw#3472), preserving strict access through Get.rootController. Three executed widget regressions failed before the fix and now pass through mount, disposal and remount.
@mahanpyk mahanpyk changed the title Stabilize GetX 5 RC for Flutter 3.47.9 and complete migration documentation Stabilize GetX 5 RC for Flutter 3.47.9 and 3.50.0 Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant